The Atari Compendium/The Atari Compendium (Toad Computers) (1994).iso/files/prgtools/mint/mgr/sparcmgr/doc.zoo/doc/usrman/doc.5

Text File | 1989-01-24 | 9.7 KB | 454 lines

'\"                        Copyright (c) 1988 Bellcore
'\"                            All Rights Reserved
'\"       Permission is granted to copy or use this program, EXCEPT that it
'\"       may not be sold for profit, the copyright notice must be reproduced
'\"       on copies, and credit should be given to Bellcore where it is due.
'\"       BELLCORE MAKES NO WARRANTY AND ACCEPTS NO LIABILITY FOR THIS PROGRAM.
'\"
'\"    $Header: doc.5,v 4.1 88/06/29 17:05:04 bianchi Exp $
'\"    $Source: /tmp/mgrsrc/doc/usrman/RCS/doc.5,v $
.Sh page Functions
The functions listed below have packaged common sequences of
.I macro
calls together to provide a slightly higher level of interface than the
macros alone.  They are still low level, and have no pretense of
completeness. Except where noted, all of the functions return a value
greater than zero on success, and a value less than zero upon failure.
The functions fail only if they read an unexpected value from \*M.
Client programs may use the function
.Fr m_lastline
in an attempt to determine what input caused the failure.
Those functions which expect data from \*M automatically flush any
pending output before reading, and unless the
.I M_MODEOK
flag is set,
attempt to turn off character echoing
to prevent data returned by \*M from echoing back on the window.
.LP
.RS
.Fd int
.Fr get_all list
.Fs get_all\(dg 7 "Get all window status"
.br
struct window_data \*Alist;
.Ft
The current position size and status of all windows on the display
is returned in
.Fi list .
The number of in
windows on the display is returned.
.Fi List
should be large enough to hold a status entry for each window.
The
.I window_data
structure
is defined in
.I term.h .
.Fd int
.Fr get_client list
.Fs get_client\(dg 7 "Get alternate window status"
.br
struct window_data \*Alist;
.Ft
The current position size and status of the client programs
.I main
and
.I alternate
windows
is returned in
.Fi list .
The number of
windows owned by the client program is returned.
.Fi List
should be large enough to hold a status entry for each window.
The
.I window_data
structure
is defined in
.I term.h .
.Fd int
.Fr get_colrow columns rows
.Fs get_colrow\(dg 7 "Get window size, in columns and rows"
.br
int \*Acolumns, \*Arows;
.Ft
The number of
.I columns
and
.I rows
in the current
.I "text region"
is returned in
.Fi columns
and
.Fi rows
respectively.
For any
.SM
.I NULL
.LG
argument,
no value is returned.
.Fd int
.Fr get_cursor column row
.Fs get_cursor\(dg 7 "Get cursor position"
.br
int \*Acolumn, \*Arow;
.Ft
The current
.I character
cursor position is placed in
.Fi column
and
.Fi row .
For any
.SM
.I NULL
.LG
argument,
no value is returned.
.Fd int
.Fr get_eachclientwin windatap
.Fs get_eachclientwin\(dg 7 "Get window parameters for each window"
.br
struct window_data \*Awindatap;
.Ft
Get the window parameters for each window in the current window set,
one window at a time.
This function returns 1 if window_data structure has been filled,
0 otherwise.
It is important to call get_eachcleintwin() in a tight loop that
doesn't exit until it returns 0,
so that all the data is picked up.
This function is preferred to
.Fr get_client
 because you don't need to know the maximum number of windows you are likely
to see.
.Fd int
.Fr get_eachwin windatap
.Fs get_eachwin\(dg 7 "Get window parameters for each window"
.br
struct window_data \*Awindatap;
.Ft
Get the window parameters for all the windows,
one window at a time.
This function returns 1 if window_data structure has been filled,
0 otherwise.
It is important to call get_eachwin() in a tight loop that
doesn't exit until it returns 0,
so that all the data is picked up.
This function is preferred to
.Fr get_all
 because you don't need to know the maximum number of windows you are likely
to see.
.Fd int
.Fr get_font wide high
.Fs get_font\(dg 7 "Get character font size"
.br
int  \*Awide, \*Ahigh;
.Ft
The character size of the current font, in pixels
is placed in
.Fi wide
and
.Fi high .
For any
.SM
.I NULL
.LG
argument,
no value is returned.
The function returns the current font number, as would be
used in a call to
.Fr m_font
\&.
.Fd int
.Fr get_mouse x y
.Fs get_mouse\(dg 7 "Get mouse position"
.br
int \*Ax, \*Ay;
.Ft
The current mouse
position, in
.I window
coordinates, is placed in
.Fi x
and
.Fi y .
For any
.SM
.I NULL
.LG
argument,
no value is returned.
The function returns the current mouse button state, which is
in the range of -2 to +2 upon success, a value less than -2
upon failure.
See
.Fr m_getinfo G_MOUSE
 for a discussion of the return values.
.Fd int
.Fr get_param host xmax ymax border
.Fs get_param\(dg 7 "Get \*M system parameters"
.br
char \*Ahost;
int \*Axmax, \*Aymax, \*Aborder;
.Ft
The
.I \*M-host ,
display size (in pixels)
and window border size (in pixels) is placed in the arguments
.Fi host , xmax , ymax ,
and
.Fi border .
For any
.SM
.I NULL
.LG
argument,
no value is returned.
.Fd int
.Fr get_size X Y Dwidth Dheight
.Fs get_size\(dg 7 "Get the window size and position on the display"
.br
int \*AX, \*AY, \*ADwidth, \*ADheight;
.Ft
The position of the window on the display, in
.I display
coordinates is placed into
.Fi X , Y , Dwidth
and
.Fi Dheight .
For any
.SM
.I NULL
.LG
argument,
no value is returned.
.Fd char \*A
.Fr get_termcap
.Fs get_termcap\(dg 7 "Get a \s-2TERMCAP\s+2 entry"
.br
.Ft
A string containing a
.I \s-2TERMCAP\s+2
entry, suitable for placing into the
.I \s-2TERMCAP\s+2
environment variable is returned.
The function
.Fr get_termcap
 returns
.SM
.I NULL
.LG
upon failure.
.Fd int
.Fs is_active\(dg 7 "See if the window is the active window"
.Fr is_active
.Ft
.br
The function
.Fr is_active
 returns
.SM
.I TRUE
.LG
if the window is the
.I active
window .
.Fd void
.Fr menu_load n count text
.Fs menu_load\(dg 8 "Down load a pop-up menu"
.br
int n;
int count;
struct menu_entry \*Atext;
.Ft
A menu is downloaded to \*M at position
.Fi n .
The integer
.Fi count
is the number of menu items to be down-loaded, and
.Fi text
is an array of menu item/value pairs.
The structure
.I menu_entry
is defined in
.I term.h .
.Fd int
.Fr m_bitfile to name widep highp
.Fs m_bitfile\(dg 5 "Read a bitmap file into a scratchpad bitmap"
.br
int to;
char *name;
int *widep, *highp;
.Ft
Given a bitmap id,
.Fi to
and an icon
.Fi name ,
have \*M load that icon into that scratchpad bitmap,
returning the icon width
and height, in pixels, via the given integer pointers.
Return a positive number if successful.
If the icon is not loaded, set the width and height values to 0 and
return 0.
This function is identical to
.Fr m_bitfromfile
plus the needed interception of the line returned from \*M.
.Fd void
.Fr m_bitload x y wide high data
.Fs m_bitload\(dg 5 "Download an image into the window"
.br
int x,y;
int wide,high;
register char \*Adata;
.Ft
The bitmap image pointed at by
.Fi data
is down-loaded to the window
at position
.Fr ""  x  y
 in
.I window
coordinates.
It is up to the client program to insure an 8 bit channel exists
between the client and \*M.
The integers
.Fi wide
and
.Fi high
specify the size of the bitmap in pixels.
.Fd char \*A
.Fr m_lastline
.Fs m_lastline\(dg 1 "Retrieve the last line send from \*M for a library function"
.br
.Ft
The last input from \*M to a library function is returned.
The data is kept in a static buffer which is overwritten
at each request.
.Fd int
.Fr m_makewindow X Y Dwidth Dheight
.Fs m_makewindow\(dg 11 "Make an alternate window"
.br
int  X, Y, Dwidth, Dheight;
.Ft
An alternate window is created as the
.I active
window,
at display coordinates
.Fr "" X Y
 and of size
.Fi Dwidth
by
.Fi Dheight
pixels.
If the window is too big to fit on the display, its
width and height are truncated.
The alternate window's
.I window-id
is returned if the window was created successfully.
The macro
.Fr m_selectwin
 is used to write on the newly created window.
.Fd int
.Fr m_setup mode
.Fs m_setup\(dg 1 "Initialize the library package"
.br
int mode;
.Ft
This function initializes the library.
It must be called before any other function or macro.
The argument
.Fi mode
is one or more of the flags
.SM
.I M_FLUSH ,
.I M_DEBUG ,
.LG
or
.SM
.I M_MODEOK
.LG
.I or -ed
together.
If
.SM
.I M_FLUSH
.LG
is present, all macros and function flush output to \*M after each
macro call.  This is slightly less efficient than letting the client
program flush the data
(see
.Fr m_flush
 )
but prevent inadvertent buffering problems.
The
.I M_DEBUG
flag forces the macro package to read and write from
.I stdin
and
.I stdout
respectively.
Normally
.I /dev/tty
is opened for reading and writing to permit standard input or output
redirection while still maintaining a connection to \*M.
If
.I /dev/tty
can not be opened, as would be the case for clients invoked through
.I rsh ,
the
.I M_DEBUG
flag is turned on,
and
.I stdin
and
.I stdout
are used instead.
The
.I M_MODEOK
flag instructs those functions which expect data from \*M
to assume the terminal modes are set appropriately.
Otherwise, the functions attempt to turn off character echoing and
turn on line mode before fetching data from \*M.
The functions
.Fr m_ttyset
 and
.Fr m_ttyreset
 can be used to set and reset the terminal modes.
The function
.Fr m_setup
 returns its argument, with the
.I M_DEBUG
flag
.I or -ed
in if
.I /dev/tty
can not be opened.
.Fd void
.Fr m_ttyreset
.Fs m_ttyreset\(dg 1 "Reset the tty modes"
.br
.Ft
The terminal modes are restored to their state just
prior to the last call to
.Fr m_ttyset
\&.
Calls to
.Fr m_ttyset
 and
.Fr m_ttyreset
 may be stacked up to ten levels.
.Fd int
.Fr m_ttyset
.Fs m_ttyset\(dg 1 "Set the tty modes for proper \*M interaction"
.br
.Ft
The terminal is set in a state suitable for data exchange with \*M.
Character echoing is turned off, and line processing mode
is enabled.
The function returns zero (0) if it successfully retrieves the terminal
modes, -1 otherwise.
.RE